<!DOCTYPE html>
<!--[if lt IE 7]>      <html class="lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]>         <html class="lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]>         <html class="lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html class=""> <!--<![endif]-->
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
     <meta property="qc:admins" content="63350727776371646636" />
  
  
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width,initial-scale=1.0,minimum-scale=1.0,maximum-scale=1.0,user-scalable=no">
  <title> SwiftV课堂 - 中国最大的Swift视频学习站</title>
  <meta name="keywords" content="swift,swift 教程,swift视频,swift论坛,swiftv课堂,swift培训,swift开发,ios8 开发,ios9 编程" />
  <meta name="description" content="SwiftV课堂是国内氛围最好的swift学习、交流网站，提供上千套swift视频,swift教程免费观看，学Swift开发(iOS10 开发)就上SwiftV课堂。" />
  <link rel="shortcut icon" type="image/x-icon" href="http://static.vlms.cn/images/2014/08/hyjpep4o.png" media="screen" />
  
  <link href="http://static.vlms.cn/resources/bootstrap/css/bootstrap.css" rel="stylesheet" />
  <link rel="stylesheet" media="screen" href="http://static.vlms.cn/resources/bootstrap/css/bootstrap-extends.css" />
  
  <!-- 预览、自定义、默认css样式  -->
  	<link rel="stylesheet" media="screen" href="http://static.vlms.cn/resources/css/schoolweb.css" />
  
  <!-- 回到顶部样式  -->
  <link rel="stylesheet" media="screen" href="http://static.vlms.cn/resources/css/upDown.css" />
  
  <script src="http://static.vlms.cn/resources/js/jquery.min.js"></script>
  <script src="http://static.vlms.cn/resources/js/main.js"></script>
  
  <!-- 回到顶部样式  -->
  <script src="http://static.vlms.cn/resources/js/JQscrollTop.js"></script>
  <script src="http://static.vlms.cn/resources/js/updown.js"></script>
  
    <!--[if lt IE 8]>
      <link href="//static.vlms.cn/resources/wangxiaoyun/css/oldie.css" rel="stylesheet">
    <![endif]-->
    
    <!--[if lt IE 9]>
    <script src="//static.vlms.cn/resources/wangxiaoyun/libs/html5shiv.js"></script>
    <![endif]-->

	  <!--[if IE 8]>
	    <script src="//static.vlms.cn/resources/wangxiaoyun/libs/respond.min.js"></script>
	  <![endif]-->
  
</head>
<body id="bodyColor" class="">

<style>
.nav-list > li.active > a {
    background-color: #ffa275;  
    color: #ffffff;
}

.site-navbar .navbar-nav > li > a:hover {
    background-color: #ffa275;
    color: #ffffff;
}
</style>

<div class="navbar navbar-inverse site-navbar" id="site-navbar">
  <div class="container">
    <div class="container-gap">
      <div class="navbar-header">
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
          <a class="navbar-brand-logo" href="../index.html">
            <img src="http://static.vlms.cn/images/2015/07/ic4hqb7b.png" alt="SwiftV课堂" title="SwiftV课堂" height="55px;" />
          </a>
      </div>
      
      <div class="navbar-collapse collapse">
          <ul class="nav navbar-nav">
              <li><a href="../course/explore-sort=latest.html"  >全部课程</a></li>
              <li><a href="https://www.boxueio.com/skill/swift?v"  target="_blank"  >如何学Swift？</a></li>
              <li><a href="../page/qun.html"  >Q群公布</a></li>
              <li><a href="../page/lianxi.html"  >联系我们</a></li>
          </ul>
        
        <ul class="nav navbar-nav navbar-right">
          <li>
	        <span class="nav navbar-nav" style="margin-top:10px;width:170px;">
	          <input class="typehead form-control search_input" type="text" placeholder="搜索课程或用户" style="display:inline;background:#5c5f68; border: 0px solid #5c5f68;width:130px;" data-role="item-input">
		      <button class="btn btn-default xin-search-btn" type="submit" data-role="item-add" style="margin-left:-10px;margin-top:-3px;background-color:#5c5f68;border: 1px solid #5c5f68;color:#a1a4ac;"><i class="glyphicon glyphicon-search"></i></button>
	    	</span>            
          </li>  
            <li><a href="../login.html">登录</a></li>
               <li><a href="../register.html">注册</a></li>
        </ul>        

      </div><!--/.navbar-collapse -->
    </div>
  </div>
</div>


<script>
   $(document).ready(function(){
      $(".typehead").click(function(){
          $(this).css("background","white");
          $(".xin-search-btn").css({"background":"white","border":"1px solid #FFFFFF"});
      });
      
   	  $(".typehead").blur(function(){
          $(this).css("background","#5c5f68");
           $(".xin-search-btn").css({"background":"#5c5f68","border":"1px solid #5c5f68"});
      });
      
	  //搜索按钮
	  $(".xin-search-btn").click(function(){
	   	var key=$(".search_input").val();
	   	var url = "";
	   	if (getUrlParam('theme')) {
	   		var value = getUrlParam('theme');
	   		url="/search/course?keyword="+key+"&theme="+value;
	   	}else{
			url="/search/course?keyword="+key;
		}
		location.href=url;
	  });
	  
	  	//获取url中的参数
		function getUrlParam(name) {
			var reg = new RegExp("(^|&)" + name + "=([^&]*)(&|$)"); //构造一个含有目标参数的正则表达式对象
			var r = window.location.search.substr(1).match(reg);  	//匹配目标参数
			if (r != null) return unescape(r[2]); return null; 		//返回参数值
		}
	
   });
</script>


<div id="content-container" class="container">
        <div class="wxy-row-wrap container-gap" style="padding:15px 26px;">
  		<div class="row form-group">
  		
			    <div class="col-md-12">
			      <div class="page-header">
			        <h1>Swift 3 SE-0023 API设计指南  <div class="pull-right" style="font-size:12px;padding:26px 20px; color:#7abaf5;">
			        <span>
		        		日期：2016-06-22 12:26:27
	        		</span>
	        		</div></h1>
			       
			      </div>
			      
			    </div>
	 
	  			<div class="col-md-12" style="padding-bottom:20px;">
			    <div class="control-label"> <label for="content">摘要：</label> </div>
			        <p style="padding-left:30px;padding-right:30px;"> 点评：原来的Objective-C API在Swift中哪些地方水土不服，所谓更原汁原味的Swift API究竟指的是什么？迁移到Swift 3，要从认真研读这份设计指南开始。
</br>
译文链接：<a href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/SE-0023%20swift-api-guidelines.md" target="_blank"><span style="color:#337FE5;"><u>https://github.com/Boxue/swift-api-design-guidelines/blob/master/SE-0023%20swift-api-guidelines.md</u></span></a><span style="line-height:1.5;"></p>
			     </div>
			     
			    <div class="col-md-12" style="padding-bottom:20px;">
			    <div class="control-label"> <label for="content">内容：</label> </div>
			        <p style="padding-left:30px;padding-right:30px;"> <h2 style="font-size:1.75em;font-family:;">
	第一部分 基本原则
</h2>
<h3 style="font-size:1.5em;font-family:;">
	<a id="user-content-11-简以至用" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#11-%E7%AE%80%E4%BB%A5%E8%87%B3%E7%94%A8"></a>1.1 简以至用
</h3>
<p style="font-family:" font-size:16px;"="">
	这是最重要的设计目标。方法（method）和属性（property）只被声明一次，却会被无数次反复使用。API的简洁和清晰是要体现在它们被使用的时候。当评估一个设计的时候，仅仅去读它的声明是远远不够的，要反复在它的使用环境里推敲这个设计，并确保它足够简洁；
	</p>
	<h3 style="font-size:1.5em;font-family:;">
		<a id="user-content-12-明确重于简短" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#12-%E6%98%8E%E7%A1%AE%E9%87%8D%E4%BA%8E%E7%AE%80%E7%9F%AD"></a>1.2 明确重于简短
	</h3>
<p style="font-family:" font-size:16px;"="">
	尽管Swift代码可以很简短，但用最少的字符去编程并不是Swift的初衷。Swift中出现的简短代码只是强类型语言带来的一个副作用而已，因为可以在类型约束下推导出很多代码，因此省略了很多不必要的代码模板；
</p>
<h3 style="font-size:1.5em;font-family:;">
	<a id="user-content-13-用文档的风格写注释" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#13-%E7%94%A8%E6%96%87%E6%A1%A3%E7%9A%84%E9%A3%8E%E6%A0%BC%E5%86%99%E6%B3%A8%E9%87%8A"></a>1.3 用文档的风格写注释
</h3>
<p style="font-family:" font-size:16px;"="">
	在每一个声明前，你应该如此。写文档时获得的灵感可以对你的设计思路有极大启发，所以，不要想着编码后回来补文档。
	</p>
<blockquote style="color:#777777;font-family:" font-size:16px;"="">
	<p>
		实际上，如果你无法三三两两就描述出API要完成的任务，<span style="font-weight:bolder;">你的API也许设计错了</span>。
	</p>
		</blockquote>
<p style="font-family:" font-size:16px;"="">
	另外，对于文档注释，还有以下补充说明：
			</p>
			<h4 style="font-size:1.25em;font-family:;">
				<a id="user-content-131-使用swift-markdown方言来编写注释" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#131-%E4%BD%BF%E7%94%A8swift-markdown%E6%96%B9%E8%A8%80%E6%9D%A5%E7%BC%96%E5%86%99%E6%B3%A8%E9%87%8A"></a>1.3.1 使用<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/">Swift Markdown方言</a>来编写注释
			</h4>
			<h4 style="font-size:1.25em;font-family:;">
				<a id="user-content-132-在任何声明之前让注释以一个摘要开始" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#132-%E5%9C%A8%E4%BB%BB%E4%BD%95%E5%A3%B0%E6%98%8E%E4%B9%8B%E5%89%8D%E8%AE%A9%E6%B3%A8%E9%87%8A%E4%BB%A5%E4%B8%80%E4%B8%AA%E6%91%98%E8%A6%81%E5%BC%80%E5%A7%8B"></a>1.3.2 在任何声明之前，（让注释）以一个摘要开始
			</h4>
<p style="font-family:" font-size:16px;"="">
	通常，应该让读者可以根据这个摘要和声明完全理解API的功能。例如：
		</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Returns a "view" of `self` containing the same elements in</span> <span class="pl-c" style="color:#969896;">/// reverse order.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">reversed</span>() <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">ReverseCollection</span></pre>
			</div>
<ul style="font-family:" font-size:16px;"="">
			<li>
				<span style="font-weight:bolder;">专注于写摘要</span> 
			</li>
				</ul>
<p style="font-family:" font-size:16px;"="">
	这是（所有注释部分中）最重要的构成。很多出色的注释文档只有一条出色的摘要。
					</p>
<ul style="font-family:" font-size:16px;"="">
					<li>
						<span style="font-weight:bolder;">使用一个单一的语句片段</span> 
					</li>
						</ul>
<p style="font-family:" font-size:16px;"="">
	如果可能，尽量避免在摘要中使用一个完整的句子。使用一个表意清晰的语句片段即可，并且使用点号（即 .）表示结束。
							</p>
<ul style="font-family:" font-size:16px;"="">
							<li>
								<span style="font-weight:bolder;">采用“描述一个函数或方法会做那些操作、返回什么”这样的句式</span> 
							</li>
								</ul>
<p style="font-family:" font-size:16px;"="">
	如果函数只是简单返回内容，就忽略掉做什么的部分；如果函数返回Void，就忽略返回值的描述，例如：
									</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Inserts `newHead` at the beginning of `self`.</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">prepend</span>(newHead: <span class="pl-c1" style="color:#0086B3;">Int</span>) <span class="pl-c" style="color:#969896;">/// Returns a `List` containing `head` followed by the elements</span> <span class="pl-c" style="color:#969896;">/// of `self`.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">prepending</span>(head: Element) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> List <span class="pl-c" style="color:#969896;">/// Removes and returns the first element of `self` if non-empty;</span> <span class="pl-c" style="color:#969896;">/// returns `nil` otherwise.</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">popFirst</span>() <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Element?</pre>
										</div>
<p style="font-family:" font-size:16px;"="">
	当然，popFirst方法出现了一些例外，我们使用了两句话描述了摘要。当遇到这种情况时，使用分号分隔开多个语句。
											</p>
<ul style="font-family:" font-size:16px;"="">
											<li>
												<span style="font-weight:bolder;">描述一个下标具体访问的元素类型</span>，例如：
											</li>
												</ul>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Accesses the `index`th element.</span> <span class="pl-k" style="color:#A71D5D;">subscript</span>(index: <span class="pl-c1" style="color:#0086B3;">Int</span>) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Element { <span class="pl-k" style="color:#A71D5D;">get</span> <span class="pl-k" style="color:#A71D5D;">set</span> }</pre>
													</div>
<ul style="font-family:" font-size:16px;"="">
													<li>
														<span style="font-weight:bolder;">描述一个init方法究竟创建了什么</span>，例如：
													</li>
														</ul>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Creates an instance containing `n` repetitions of `x`.</span> <span class="pl-k" style="color:#A71D5D;">init</span>(count n: <span class="pl-c1" style="color:#0086B3;">Int</span>, repeatedElement x: Element)</pre>
															</div>
<ul style="font-family:" font-size:16px;"="">
															<li>
																<span style="font-weight:bolder;">对于其它的声明来说，描述它们是什么</span>，例如：
															</li>
																</ul>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// A collection that supports equally efficient insertion/removal</span> <span class="pl-c" style="color:#969896;">/// at any position.</span> <span class="pl-k" style="color:#A71D5D;">struct</span> List { <span class="pl-c" style="color:#969896;">/// The element at the beginning of `self`, or `nil` if self is</span> <span class="pl-c" style="color:#969896;">/// empty.</span> <span class="pl-k" style="color:#A71D5D;">var</span> first: Element? <span class="pl-k" style="color:#A71D5D;">...</span></pre>
																	</div>
																	<h4 style="font-size:1.25em;font-family:;">
																		<a id="user-content-133-这条是可选的在summary之后用一系列段落和列表项来对声明进行补充说明" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#133-%E8%BF%99%E6%9D%A1%E6%98%AF%E5%8F%AF%E9%80%89%E7%9A%84%E5%9C%A8summary%E4%B9%8B%E5%90%8E%E7%94%A8%E4%B8%80%E7%B3%BB%E5%88%97%E6%AE%B5%E8%90%BD%E5%92%8C%E5%88%97%E8%A1%A8%E9%A1%B9%E6%9D%A5%E5%AF%B9%E5%A3%B0%E6%98%8E%E8%BF%9B%E8%A1%8C%E8%A1%A5%E5%85%85%E8%AF%B4%E6%98%8E"></a>1.3.3 这条是可选的，（在summary之后），用一系列段落和列表项来对声明进行补充说明
																	</h4>
<p style="font-family:" font-size:16px;"="">
	段落之间用一个空行表示，并且在每一段中使用完整的语句描述。例如：
																		</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Writes the textual representation of each    ← Summary</span> <span class="pl-c" style="color:#969896;">/// element of `items` to the standard output.</span> <span class="pl-c" style="color:#969896;">///                                              ← Blank line</span> <span class="pl-c" style="color:#969896;">/// The textual representation for each item `x` ← Additional discussion</span> <span class="pl-c" style="color:#969896;">/// is generated by the expression `String(x)`.</span> <span class="pl-c" style="color:#969896;">///</span> <span class="pl-c" style="color:#969896;">/// - Parameter separator: text to be printed    ⎫</span> <span class="pl-c" style="color:#969896;">///   between items.                             ⎟</span> <span class="pl-c" style="color:#969896;">/// - Parameter terminator: text to be printed   ⎬ Parameters section</span> <span class="pl-c" style="color:#969896;">///   at the end.                                ⎟</span> <span class="pl-c" style="color:#969896;">///                                              ⎭</span> <span class="pl-c" style="color:#969896;">/// - Note: To print without a trailing          ⎫</span> <span class="pl-c" style="color:#969896;">///   newline, pass `terminator: ""`             ⎟</span> <span class="pl-c" style="color:#969896;">///                                              ⎬ Symbol commands</span> <span class="pl-c" style="color:#969896;">/// - SeeAlso: `CustomDebugStringConvertible`,   ⎟</span> <span class="pl-c" style="color:#969896;">///   `CustomStringConvertible`, `debugPrint`.   ⎭</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">print</span>(
  items: <span class="pl-c1" style="color:#0086B3;">Any</span><span class="pl-k" style="color:#A71D5D;">...</span>, separator: <span class="pl-c1" style="color:#0086B3;">String</span> <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-s" style="color:#183691;"><span class="pl-pds">"</span> <span class="pl-pds">"</span></span>, terminator: <span class="pl-c1" style="color:#0086B3;">String</span> <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-s" style="color:#183691;"><span class="pl-pds">"</span><span class="pl-cce">\n</span><span class="pl-pds">"</span></span>)</pre>
																			</div>
<ul style="font-family:" font-size:16px;"="">
																			<li>
																				合适的时候，在注释中使用<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/SymbolDocumentation.html#/apple_ref/doc/uid/TP40016497-CH51-SW1">Markdown标记注释文档</a>；
																			</li>
																			<li>
																				<span style="font-weight:bolder;">了解并使用<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/SymbolDocumentation.html#/apple_ref/doc/uid/TP40016497-CH51-SW13">symbol command syntax</a>在文档突出特定内容</span> 
																			</li>
																				</ul>
<p style="font-family:" font-size:16px;"="">
	一些流行的开发工具，例如：Xcode，可以对文档中的下列关键字做特殊处理，并突出显示它们：
																					</p>
<p style="font-family:" font-size:16px;"=""> <a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Attention.html">Attention</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Author.html">Author</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Authors.html">Authors</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Bug.html">Bug</a>&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Complexity.html">Complexity</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Copyright.html">Copyright</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Date.html">Date</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Experiment.html">Experiment</a>&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Important.html">Important</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Invariant.html">Invariant</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Note.html">Note</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Parameter.html">Parameter</a><a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Parameters.html">Parameters</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Postcondition.html">Postcondition</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Precondition.html">Precondition</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Remark.html">Remark</a>&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Requires.html">Requires</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Returns.html">Returns</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/SeeAlso.html">SeeAlso</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Since.html">Since</a>&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Throws.html">Throws</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Todo.html">Todo</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Version.html">Version</a>&nbsp;|&nbsp;<a href="https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Warning.html">Warning</a> 
																				</p>
																				<h2 style="font-size:1.75em;font-family:;">
																					<a id="user-content-第二部分-命名规则" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#%E7%AC%AC%E4%BA%8C%E9%83%A8%E5%88%86-%E5%91%BD%E5%90%8D%E8%A7%84%E5%88%99"></a>第二部分 命名规则
																				</h2>
																				<h3 style="font-size:1.5em;font-family:;">
																					<a id="user-content-21-为了更清晰的用法而改进" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#21-%E4%B8%BA%E4%BA%86%E6%9B%B4%E6%B8%85%E6%99%B0%E7%9A%84%E7%94%A8%E6%B3%95%E8%80%8C%E6%94%B9%E8%BF%9B"></a>2.1 为了更清晰的用法而改进
																				</h3>
																				<h4 style="font-size:1.25em;font-family:;">
																					<a id="user-content-211-包含所有为了避免歧义的单词" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#211-%E5%8C%85%E5%90%AB%E6%89%80%E6%9C%89%E4%B8%BA%E4%BA%86%E9%81%BF%E5%85%8D%E6%AD%A7%E4%B9%89%E7%9A%84%E5%8D%95%E8%AF%8D"></a>2.1.1 包含所有为了避免歧义的单词
																				</h4>
<p style="font-family:" font-size:16px;"="">
	包含所有当阅读代码时会引起歧义的单词。例如：定义一个在集合中删除元素的方法：
																					</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> List { <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">remove</span>(<span class="pl-en" style="color:#795DA3;">at</span> <span class="pl-smi">position</span>: Index) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Element
}
employees<span class="pl-k" style="color:#A71D5D;">.</span>remove(at: x)</pre>
																						</div>
<p style="font-family:" font-size:16px;"="">
	如果忽略掉函数签名中的at，remove就会被人误解为在集合中搜索x并且删除，而不是把x当成要删除元素的索引。
																							</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>employees<span class="pl-k" style="color:#A71D5D;">.</span>remove(x) <span class="pl-c" style="color:#969896;">// unclear: are we removing x?</span></pre>
																								</div>
																								<h4 style="font-size:1.25em;font-family:;">
																									<a id="user-content-212-忽略不需要的单词" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#212-%E5%BF%BD%E7%95%A5%E4%B8%8D%E9%9C%80%E8%A6%81%E7%9A%84%E5%8D%95%E8%AF%8D"></a>2.1.2 忽略不需要的单词
																								</h4>
<p style="font-family:" font-size:16px;"="">
	每一个单词都应该为它自己的表意尽职尽责。用更多单词来表明含义或避免混淆是没问题的。但是，对于那些读者已经可以顺利推断出含义的词，应该被忽略，特别是那些仅仅用来重复类型信息的词。例如：
																									</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">removeElement</span>(member: Element) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Element?
allViews<span class="pl-k" style="color:#A71D5D;">.</span>removeElement(cancelButton)</pre>
																										</div>
<p style="font-family:" font-size:16px;"="">
	在这个例子里，Element没有在调用时传递更多有用的信息。把API设计成这样会更好：
																											</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">remove</span>(member: Element) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Element?
allViews<span class="pl-k" style="color:#A71D5D;">.</span>remove(cancelButton) <span class="pl-c" style="color:#969896;">// clearer</span></pre>
																												</div>
<p style="font-family:" font-size:16px;"="">
	有时，重复类型信息是必要的，它可以避免混淆，但大多数时候，我们应该用一个单词来描述参数承担的角色而不是它的类型。具体参考下一条。
																													</p>
																													<h4 style="font-size:1.25em;font-family:;">
																														<a id="user-content-213-根据变量参数以及关联类型associated-type的角色为它们命名而不是根据它们的类型约束为它们命名" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#213-%E6%A0%B9%E6%8D%AE%E5%8F%98%E9%87%8F%E5%8F%82%E6%95%B0%E4%BB%A5%E5%8F%8A%E5%85%B3%E8%81%94%E7%B1%BB%E5%9E%8Bassociated-type%E7%9A%84%E8%A7%92%E8%89%B2%E4%B8%BA%E5%AE%83%E4%BB%AC%E5%91%BD%E5%90%8D%E8%80%8C%E4%B8%8D%E6%98%AF%E6%A0%B9%E6%8D%AE%E5%AE%83%E4%BB%AC%E7%9A%84%E7%B1%BB%E5%9E%8B%E7%BA%A6%E6%9D%9F%E4%B8%BA%E5%AE%83%E4%BB%AC%E5%91%BD%E5%90%8D"></a>2.1.3 根据变量、参数以及关联类型（associated type）的角色为它们命名，而不是根据它们的类型约束为它们命名
																													</h4>
<p style="font-family:" font-size:16px;"="">
	例如：
																												</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">var</span> string <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-s" style="color:#183691;"><span class="pl-pds">"</span>Hello<span class="pl-pds">"</span></span> <span class="pl-k" style="color:#A71D5D;">protocol</span> ViewController {
    associatedtype ViewType <span class="pl-k" style="color:#A71D5D;">:</span> View
} <span class="pl-k" style="color:#A71D5D;">class</span> ProductionLine { <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">restock</span>(<span class="pl-en" style="color:#795DA3;">from</span> <span class="pl-smi">widgetFactory</span>: WidgetFactory)
}</pre>
																											</div>
<p style="font-family:" font-size:16px;"="">
	像上面这样把类型当成名称来用并不会提高代码的简洁性和可读性。我们应该基于一个实体的角色来为它命名，像这样：
																										</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">var</span> greeting <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-s" style="color:#183691;"><span class="pl-pds">"</span>Hello<span class="pl-pds">"</span></span> <span class="pl-k" style="color:#A71D5D;">protocol</span> ViewController {
    associatedtype ContentView <span class="pl-k" style="color:#A71D5D;">:</span> View
} <span class="pl-k" style="color:#A71D5D;">class</span> ProductionLine { <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">restock</span>(<span class="pl-en" style="color:#795DA3;">from</span> <span class="pl-smi">supplier</span>: WidgetFactory)
}</pre>
																									</div>
<p style="font-family:" font-size:16px;"="">
	如果associatedtype和protocol关联性非常强，甚至protocol的名称就是associatedtype要承担的角色。此时，为了避免名称冲突，应该在associatedtype的名称末尾添加Type后缀，例如：
																								</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">protocol</span> Sequence {
    associatedtype IteratorType <span class="pl-k" style="color:#A71D5D;">:</span> Iterator
}</pre>
																							</div>
																							<h4 style="font-size:1.25em;font-family:;">
																								<a id="user-content-214-为弱类型信息参数承担的角色提供补偿" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#214-%E4%B8%BA%E5%BC%B1%E7%B1%BB%E5%9E%8B%E4%BF%A1%E6%81%AF%E5%8F%82%E6%95%B0%E6%89%BF%E6%8B%85%E7%9A%84%E8%A7%92%E8%89%B2%E6%8F%90%E4%BE%9B%E8%A1%A5%E5%81%BF"></a>2.1.4 为弱类型信息参数承担的角色提供补偿
																							</h4>
<p style="font-family:" font-size:16px;"="">
	特别是一个参数的类型是NSObject，Any，AnyObject或者是Int或String这样的基本类型时，类型自带信息和使用它们的上下文不能充分表达它们的使用意图。例如，对于下面这个例子来说，看声明是清晰的，但用起来，确是含糊的。
																						</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">add</span>(observer: NSObject, <span class="pl-en" style="color:#795DA3;">for</span> <span class="pl-smi">keyPath</span>: <span class="pl-c1" style="color:#0086B3;">String</span>)
grid<span class="pl-k" style="color:#A71D5D;">.</span>add(<span class="pl-k" style="color:#A71D5D;">self</span>, <span class="pl-k" style="color:#A71D5D;">for</span>: graphics) <span class="pl-c" style="color:#969896;">// vague</span></pre>
																					</div>
<p style="font-family:" font-size:16px;"="">
	为了解决这个问题，<span style="font-weight:bolder;">在每个弱类型信息参数前面，加上一个表示角色的名词</span>：
																				</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">addObserver</span>(<span class="pl-en" style="color:#795DA3;">_</span> <span class="pl-smi">observer</span>: NSObject, <span class="pl-en" style="color:#795DA3;">forKeyPath</span> <span class="pl-smi">path</span>: <span class="pl-c1" style="color:#0086B3;">String</span>)
grid<span class="pl-k" style="color:#A71D5D;">.</span>addObserver(<span class="pl-k" style="color:#A71D5D;">self</span>, forKeyPath: graphics) <span class="pl-c" style="color:#969896;">// clear</span></pre>
																					</div>
																					<h3 style="font-size:1.5em;font-family:;">
																						<a id="user-content-22-尽全力做到使用连贯" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#22-%E5%B0%BD%E5%85%A8%E5%8A%9B%E5%81%9A%E5%88%B0%E4%BD%BF%E7%94%A8%E8%BF%9E%E8%B4%AF"></a>2.2 尽全力做到使用连贯
																					</h3>
																					<h4 style="font-size:1.25em;font-family:;">
																						<a id="user-content-221-倾向于那些在使用时可以形成正确英语语法的名字" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#221-%E5%80%BE%E5%90%91%E4%BA%8E%E9%82%A3%E4%BA%9B%E5%9C%A8%E4%BD%BF%E7%94%A8%E6%97%B6%E5%8F%AF%E4%BB%A5%E5%BD%A2%E6%88%90%E6%AD%A3%E7%A1%AE%E8%8B%B1%E8%AF%AD%E8%AF%AD%E6%B3%95%E7%9A%84%E5%90%8D%E5%AD%97"></a>2.2.1 倾向于那些在使用时可以形成正确英语语法的名字
																					</h4>
<p style="font-family:" font-size:16px;"="">
	例如，下面这些表达方式是正确的：
																						</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>x<span class="pl-k" style="color:#A71D5D;">.</span><span class="pl-c1" style="color:#0086B3;">insert</span>(y, at: z)          “x, <span class="pl-c1" style="color:#0086B3;">insert</span> y at z”
x<span class="pl-k" style="color:#A71D5D;">.</span>subViews(havingColor: y)  “x's subviews having color y”
x<span class="pl-k" style="color:#A71D5D;">.</span>capitalizingNouns()       “x, capitalizing nouns”</pre>
																							</div>
<p style="font-family:" font-size:16px;"="">
	而下面这些则是错误的：
																								</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>x<span class="pl-k" style="color:#A71D5D;">.</span><span class="pl-c1" style="color:#0086B3;">insert</span>(y, position: z)
x<span class="pl-k" style="color:#A71D5D;">.</span>subViews(color: y)
x<span class="pl-k" style="color:#A71D5D;">.</span>nounCapitalize()</pre>
																									</div>
<p style="font-family:" font-size:16px;"="">
	通常，对于那些在调用时，不影响方法核心语义的参数，为了表意的连贯，让他们的参数有更简单的形式也是可接受的。例如：
																										</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>AudioUnit<span class="pl-k" style="color:#A71D5D;">.</span>instantiate(
    with: description,
    options: [<span class="pl-k" style="color:#A71D5D;">.</span>inProcess], completionHandler: stopProgressBar)</pre>
																											</div>
																											<h4 style="font-size:1.25em;font-family:;">
																												<a id="user-content-222-在工厂方法的名字前使用make例如xmakeiterator" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#222-%E5%9C%A8%E5%B7%A5%E5%8E%82%E6%96%B9%E6%B3%95%E7%9A%84%E5%90%8D%E5%AD%97%E5%89%8D%E4%BD%BF%E7%94%A8make%E4%BE%8B%E5%A6%82xmakeiterator"></a>2.2.2 在工厂方法的名字前使用make，例如：x.makeIterator()；
																											</h4>
																											<h5 style="font-size:1em;font-family:;">
																												<a id="user-content-2221-对于构造函数和工厂方法来说调用它们时形成的英文语句中不应包含第一个参数例如下面的代码是正确的" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#2221-%E5%AF%B9%E4%BA%8E%E6%9E%84%E9%80%A0%E5%87%BD%E6%95%B0%E5%92%8C%E5%B7%A5%E5%8E%82%E6%96%B9%E6%B3%95%E6%9D%A5%E8%AF%B4%E8%B0%83%E7%94%A8%E5%AE%83%E4%BB%AC%E6%97%B6%E5%BD%A2%E6%88%90%E7%9A%84%E8%8B%B1%E6%96%87%E8%AF%AD%E5%8F%A5%E4%B8%AD%E4%B8%8D%E5%BA%94%E5%8C%85%E5%90%AB%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E4%BE%8B%E5%A6%82%E4%B8%8B%E9%9D%A2%E7%9A%84%E4%BB%A3%E7%A0%81%E6%98%AF%E6%AD%A3%E7%A1%AE%E7%9A%84"></a>2.2.2.1 对于构造函数和工厂方法来说，调用它们时形成的英文语句中不应包含第一个参数，例如，下面的代码是正确的：
																											</h5>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">let</span> foreground <span class="pl-k" style="color:#A71D5D;">=</span> Color(red: <span class="pl-c1" style="color:#0086B3;">32</span>, green: <span class="pl-c1" style="color:#0086B3;">64</span>, blue: <span class="pl-c1" style="color:#0086B3;">128</span>) <span class="pl-k" style="color:#A71D5D;">let</span> newPart <span class="pl-k" style="color:#A71D5D;">=</span> factory<span class="pl-k" style="color:#A71D5D;">.</span>makeWidget(gears: <span class="pl-c1" style="color:#0086B3;">42</span>, spindles: <span class="pl-c1" style="color:#0086B3;">14</span>)</pre>
																										</div>
<p style="font-family:" font-size:16px;"="">
	在下面的代码中，API的作者尝试在方法被调用时，通过第一个参数的名字创建语法连贯的表达方式（但这样是错误的）：
																									</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">let</span> foreground <span class="pl-k" style="color:#A71D5D;">=</span> Color(havingRGBValuesRed: <span class="pl-c1" style="color:#0086B3;">32</span>, green: <span class="pl-c1" style="color:#0086B3;">64</span>, andBlue: <span class="pl-c1" style="color:#0086B3;">128</span>) <span class="pl-k" style="color:#A71D5D;">let</span> newPart <span class="pl-k" style="color:#A71D5D;">=</span> factory<span class="pl-k" style="color:#A71D5D;">.</span>makeWidget(havingGearCount: <span class="pl-c1" style="color:#0086B3;">42</span>, andSpindleCount: <span class="pl-c1" style="color:#0086B3;">14</span>)</pre>
																								</div>
<p style="font-family:" font-size:16px;"="">
	实际上，这条原则和下面对参数命名的原则一起，决定了绝大多数时候，（构造函数和工厂方法）的第一个参数总是会有external name的。除非，调用时体现的是一个“无损类型转换（full-width type conversion）”
																							</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">let</span> rgbForeground <span class="pl-k" style="color:#A71D5D;">=</span> RGBColor(cmykForeground)</pre>
																						</div>
																						<h5 style="font-size:1em;font-family:;">
																							<a id="user-content-2222-根据函数或方法的副作用为它们命名" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#2222-%E6%A0%B9%E6%8D%AE%E5%87%BD%E6%95%B0%E6%88%96%E6%96%B9%E6%B3%95%E7%9A%84%E5%89%AF%E4%BD%9C%E7%94%A8%E4%B8%BA%E5%AE%83%E4%BB%AC%E5%91%BD%E5%90%8D"></a>2.2.2.2 根据函数或方法的副作用为它们命名
																						</h5>
<ul style="font-family:" font-size:16px;"="">
																						<li>
																							没有副作用的方法或函数应该使用一个名词表达方式，例如：x.distance(to: y)或i.successor()；
																						</li>
																						<li>
																							有副作用的方法或函数应该使用一个使役动词命名，例如：print(x)，x.sort()，x.append(y)；
																						</li>
																						<li>
																							<span style="font-weight:bolder;">总是成对命名mutating和non mutating方法</span>。一个mutating方法通常会伴随一个non mutating变体，它们表达类似的语义，但是non mutating版本返回一个新对象，而不是在原有对象上就地处理；
																							<ul>
																								<li>
																									当方法<span style="font-weight:bolder;">原生通过动词表现时</span>，用这个使役动词命名方法的mutating版本，在这个使役动词后面添加ed或ing后缀命名对应的non mutating版本；
																									<ul>
																										<li>
																											例如：mutating -&nbsp;x.sort()，non mutating -&nbsp;x.sorted()
																										</li>
																										<li>
																											例如：mutating -&nbsp;x.append(y)，non mutating -&nbsp;x.appedning(y)
																										</li>
																									</ul>
																								</li>
																								<li>
																									当方法<span style="font-weight:bolder;">原生通过名词表现时</span>，使用名词来命名方法的non mutating版本，在名词前添加form定义mutating版本；
																									<ul>
																										<li>
																											例如：non mutating -&nbsp;x.union(z)，mutating -&nbsp;y.formUnion(z)
																										</li>
																										<li>
																											例如：non mutating -&nbsp;c.successor(i)，mutating -&nbsp;y.formSuccessor(&amp;i)
																										</li>
																									</ul>
																								</li>
																							</ul>
																						</li>
																							</ul>
<p style="font-family:" font-size:16px;"=""> <span style="font-weight:bolder;">关于ed和ing的补充说明</span> 
																								</p>
<p style="font-family:" font-size:16px;"=""> <em><span style="font-weight:bolder;">应优先考虑使用动词的过去分词为non mutating方法命名（通常是ed结尾）</span></em> 
																							</p>
<p style="font-family:" font-size:16px;"="">
	例如：
																								</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Reverses self in-place.</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">reverse</span>() <span class="pl-c" style="color:#969896;">/// Returns a reversed copy of self.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">reversed</span>() <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Self <span class="pl-k" style="color:#A71D5D;">...</span> x<span class="pl-k" style="color:#A71D5D;">.</span><span class="pl-c1" style="color:#0086B3;">reverse</span>() <span class="pl-k" style="color:#A71D5D;">let</span> y <span class="pl-k" style="color:#A71D5D;">=</span> x<span class="pl-k" style="color:#A71D5D;">.</span>reversed()</pre>
																									</div>
<p style="font-family:" font-size:16px;"=""> <em><span style="font-weight:bolder;">当动词带有一个直接宾语导致添加ed会造成语法错误时，使用动词的现在进行时（添加ing）为non mutating方法命名</span></em> 
																										</p>
<p style="font-family:" font-size:16px;"="">
	例如：
																									</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Strips all the newlines from self</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">stripNewlines</span>() <span class="pl-c" style="color:#969896;">/// Returns a copy of self with all the newlines stripped.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">strippingNewlines</span>() <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">String</span> <span class="pl-k" style="color:#A71D5D;">...</span> s<span class="pl-k" style="color:#A71D5D;">.</span>stripNewlines() <span class="pl-k" style="color:#A71D5D;">let</span> oneLine <span class="pl-k" style="color:#A71D5D;">=</span> t<span class="pl-k" style="color:#A71D5D;">.</span>strippingNewlines()</pre>
																								</div>
																								<h5 style="font-size:1em;font-family:;">
																									<a id="user-content-2223-使用bool语义的方法或属性时当这是一个non-mutating操作时它们读上去应该像是对调用对象的断言" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#2223-%E4%BD%BF%E7%94%A8bool%E8%AF%AD%E4%B9%89%E7%9A%84%E6%96%B9%E6%B3%95%E6%88%96%E5%B1%9E%E6%80%A7%E6%97%B6%E5%BD%93%E8%BF%99%E6%98%AF%E4%B8%80%E4%B8%AAnon-mutating%E6%93%8D%E4%BD%9C%E6%97%B6%E5%AE%83%E4%BB%AC%E8%AF%BB%E4%B8%8A%E5%8E%BB%E5%BA%94%E8%AF%A5%E5%83%8F%E6%98%AF%E5%AF%B9%E8%B0%83%E7%94%A8%E5%AF%B9%E8%B1%A1%E7%9A%84%E6%96%AD%E8%A8%80"></a>2.2.2.3 使用Bool语义的方法或属性时，当这是一个non mutating操作时，它们读上去应该像是对调用对象的断言
																								</h5>
<p style="font-family:" font-size:16px;"="">
	例如：x.isEmpty，line1.intersects(line2)。
																							</p>
																							<h5 style="font-size:1em;font-family:;">
																								<a id="user-content-2224-如果protocol用于为某种事物进行定义这个protocol应该使用名词命名" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#2224-%E5%A6%82%E6%9E%9Cprotocol%E7%94%A8%E4%BA%8E%E4%B8%BA%E6%9F%90%E7%A7%8D%E4%BA%8B%E7%89%A9%E8%BF%9B%E8%A1%8C%E5%AE%9A%E4%B9%89%E8%BF%99%E4%B8%AAprotocol%E5%BA%94%E8%AF%A5%E4%BD%BF%E7%94%A8%E5%90%8D%E8%AF%8D%E5%91%BD%E5%90%8D"></a>2.2.2.4 如果protocol用于为某种事物进行定义，这个protocol应该使用名词命名
																							</h5>
<p style="font-family:" font-size:16px;"="">
	例如：Collecion。
																								</p>
																								<h5 style="font-size:1em;font-family:;">
																									<a id="user-content-2225-如果protocol用于表达某种事物的能力这个protocol的名字应该使用ableible或ing后缀" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#2225-%E5%A6%82%E6%9E%9Cprotocol%E7%94%A8%E4%BA%8E%E8%A1%A8%E8%BE%BE%E6%9F%90%E7%A7%8D%E4%BA%8B%E7%89%A9%E7%9A%84%E8%83%BD%E5%8A%9B%E8%BF%99%E4%B8%AAprotocol%E7%9A%84%E5%90%8D%E5%AD%97%E5%BA%94%E8%AF%A5%E4%BD%BF%E7%94%A8ableible%E6%88%96ing%E5%90%8E%E7%BC%80"></a>2.2.2.5 如果protocol用于表达某种事物的能力，这个protocol的名字，应该使用able，ible或ing后缀
																								</h5>
<p style="font-family:" font-size:16px;"="">
	例如：Equatable，ProgressReporting。
																							</p>
																							<h5 style="font-size:1em;font-family:;">
																								<a id="user-content-2226-其它的类型属性变量和常量应该使用名词" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#2226-%E5%85%B6%E5%AE%83%E7%9A%84%E7%B1%BB%E5%9E%8B%E5%B1%9E%E6%80%A7%E5%8F%98%E9%87%8F%E5%92%8C%E5%B8%B8%E9%87%8F%E5%BA%94%E8%AF%A5%E4%BD%BF%E7%94%A8%E5%90%8D%E8%AF%8D"></a>2.2.2.6 其它的<span style="font-weight:bolder;">类型、属性、变量和常量应该使用名词</span>；
																							</h5>
																							<h3 style="font-size:1.5em;font-family:;">
																								<a id="user-content-23-正确使用专业术语" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#23-%E6%AD%A3%E7%A1%AE%E4%BD%BF%E7%94%A8%E4%B8%93%E4%B8%9A%E6%9C%AF%E8%AF%AD"></a>2.3 正确使用专业术语
																							</h3>
<p style="font-family:" font-size:16px;"=""> <span style="font-weight:bolder;">Term of Art</span> 
																								</p>
<p style="font-family:" font-size:16px;"="">
	Term of Art - 指一个在特定领域或专业里，有明确特殊含义的名词或短语(fn)。
																							</p>
																							<h4 style="font-size:1.25em;font-family:;">
																								<a id="user-content-231-避免使用复杂晦涩的单词" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#231-%E9%81%BF%E5%85%8D%E4%BD%BF%E7%94%A8%E5%A4%8D%E6%9D%82%E6%99%A6%E6%B6%A9%E7%9A%84%E5%8D%95%E8%AF%8D"></a>2.3.1 避免使用复杂晦涩的单词
																							</h4>
<p style="font-family:" font-size:16px;"="">
	如果有更为常用的单词表达同样的含义，就避免使用复杂晦涩的单词。例如，（当我们要表达“表皮”这个含义的时候），如果“skin”已经充分表达意图了，就不要使用“epidermis”。虽然专业术语是重要的沟通方式，但只有需要表达重要含义，使用普通词会导致信息丢失的时候，才使用专业术语。
																								</p>
																								<h4 style="font-size:1.25em;font-family:;">
																									<a id="user-content-232-如果使用term-of-art就始终坚持它在特定领域的含义" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#232-%E5%A6%82%E6%9E%9C%E4%BD%BF%E7%94%A8term-of-art%E5%B0%B1%E5%A7%8B%E7%BB%88%E5%9D%9A%E6%8C%81%E5%AE%83%E5%9C%A8%E7%89%B9%E5%AE%9A%E9%A2%86%E5%9F%9F%E7%9A%84%E5%90%AB%E4%B9%89"></a>2.3.2 如果使用term of art，就始终坚持它在特定领域的含义
																								</h4>
<p style="font-family:" font-size:16px;"="">
	唯一一个需要使用专业术语，而不是普通单词的场景，就是需要严谨准确的表达某些含义，而使用非术语会带来歧义的时候。
																							</p>
<p style="font-family:" font-size:16px;"="">
	因此，如果API中使用了专业术语，就要坚持使用这个术语被广为接受的含义(fn)。
																								</p>
<ul style="font-family:" font-size:16px;"="">
																								<li>
																									<span style="font-weight:bolder;">不要让专家感到意外</span>：不要使用专业术语单词的其它含义，这会让特定领域的专业人员赶到意外，甚至愤怒；
																								</li>
																								<li>
																									<span style="font-weight:bolder;">不要让初学者感到困惑</span>：当一些初学者尝试理解专业术语时，他们可能会在Web上找到这些单词的非专业领域含义（注：言外之意也就是仅在必要的时候才使用专业术语）；
																								</li>
																									</ul>
																									<h4 style="font-size:1.25em;font-family:;">
																										<a id="user-content-233-避免使用缩写" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#233-%E9%81%BF%E5%85%8D%E4%BD%BF%E7%94%A8%E7%BC%A9%E5%86%99"></a>2.3.3 避免使用缩写
																									</h4>
<p style="font-family:" font-size:16px;"="">
	尤其是对于那些仅在特定领域里才使用的缩写，他们就像特定人群使用的暗号一样，高效并且有局限性。是否能正确理解它们的含义，完全取决于是否可以正确的“猜”出缩写的各个单词。
																										</p>
<blockquote style="color:#777777;font-family:" font-size:16px;"="">
																										<p>
																											因此，当一定要使用缩写时，至少让你的缩写可以很方便的在搜索引擎找到（没有歧义）的解释。
																										</p>
																											</blockquote>
																											<h4 style="font-size:1.25em;font-family:;">
																												<a id="user-content-234-尊重专业习惯" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#234-%E5%B0%8A%E9%87%8D%E4%B8%93%E4%B8%9A%E4%B9%A0%E6%83%AF"></a>2.3.4 尊重专业习惯
																											</h4>
<p style="font-family:" font-size:16px;"="">
	不要以牺牲专业习惯为代价，尝试让新手更容易理解专业术语。例如：
																												</p>
<ul style="font-family:" font-size:16px;"="">
																												<li>
																													把一段（内存）连续的数据结构定义为Array比定义成List要好的多。尽管对于新手来说，List可能更容易表现出“一列事物”这样的概念。在现代计算机中，Array是很基础的概念，所以每一个开发者都应该知道，或者立即去了解，什么是一个Array。尝试使用开发者都熟知的词汇，初学者会在提问和使用搜索引擎时，更容易获得帮助；
																												</li>
																												<li>
																													在某个特定领域里，例如数学，使用sin(x)表示正弦函数依然是众所周知的事情，使用诸如verticalPositionOnUnitCircleAtOriginOfEndOfRadiusWithAngle(x)这样的方式反而让人觉得不知所云（尽管这是在解释什么是正弦）。另外，尽管我们刚刚说过避免使用缩写，却又使用了sin(x)替代了sine(x)。是的，这次，专业习惯在决策考量中占据了更大的比重。数十年来，任何和数学打交道的从业者们已然习惯了使用sin(x)，我们应该尊重这个习惯。
																												</li>
																													</ul>
																													<h2 style="font-size:1.75em;font-family:;">
																														<a id="user-content-第三部分-约定俗成" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#%E7%AC%AC%E4%B8%89%E9%83%A8%E5%88%86-%E7%BA%A6%E5%AE%9A%E4%BF%97%E6%88%90"></a>第三部分 约定俗成
																													</h2>
																													<h3 style="font-size:1.5em;font-family:;">
																														<a id="user-content-31-一般习俗" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#31-%E4%B8%80%E8%88%AC%E4%B9%A0%E4%BF%97"></a>3.1 一般习俗
																													</h3>
																													<h4 style="font-size:1.25em;font-family:;">
																														<a id="user-content-311-使用文档明确标注哪些算法复杂度不是o1的computed-property" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#311-%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3%E6%98%8E%E7%A1%AE%E6%A0%87%E6%B3%A8%E5%93%AA%E4%BA%9B%E7%AE%97%E6%B3%95%E5%A4%8D%E6%9D%82%E5%BA%A6%E4%B8%8D%E6%98%AFo1%E7%9A%84computed-property"></a>3.1.1 使用文档明确标注哪些算法复杂度不是O(1)的computed property
																													</h4>
<p style="font-family:" font-size:16px;"="">
	人们通常会认为访问一个computed property不会带来严重的性能损耗，因为在使用它们的时候，和使用一个stored property是感受不到区别的。因此，当computed property会引起性能问题时，要明确告知开发者。
																														</p>
																														<h4 style="font-size:1.25em;font-family:;">
																															<a id="user-content-312-相比自由函数free-function更倾向于使用方法和属性解决问题" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#312-%E7%9B%B8%E6%AF%94%E8%87%AA%E7%94%B1%E5%87%BD%E6%95%B0free-function%E6%9B%B4%E5%80%BE%E5%90%91%E4%BA%8E%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95%E5%92%8C%E5%B1%9E%E6%80%A7%E8%A7%A3%E5%86%B3%E9%97%AE%E9%A2%98"></a>3.1.2 相比自由函数（free function），更倾向于使用方法和属性解决问题
																														</h4>
<p style="font-family:" font-size:16px;"="">
	仅在一些特定的情况使用自由函数。例如：
																													</p>
<ol style="font-family:" font-size:16px;"="">
																													<li>
																														要完成的任务不针对特定的self对象：min(x, y, z)；
																													</li>
																													<li>
																														函数用于执行通用性功能：print(x)；
																													</li>
																													<li>
																														调用函数的语法在特定领域里属于“习惯性用法”：sin(x)；
																													</li>
																														</ol>
																														<h4 style="font-size:1.25em;font-family:;">
																															<a id="user-content-313-使用以下命名方式" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#313-%E4%BD%BF%E7%94%A8%E4%BB%A5%E4%B8%8B%E5%91%BD%E5%90%8D%E6%96%B9%E5%BC%8F"></a>3.1.3 使用以下命名方式
																														</h4>
<p style="font-family:" font-size:16px;"="">
	类型和protocols使用UpperCamelCase进行命名，其它都使用lowerCamelCase命名。对于“首字母缩略词（Acronyms and Initialisms）”则采用以下原则：
																															</p>
<ul style="font-family:" font-size:16px;"="">
																															<li>
																																美式英语中常用的由全大写字母构成的的“首字母缩略词”应该根据使用的上下文环境，统一使用大写或小写字母，例如：
																															</li>
																																</ul>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">var</span> utf8Bytes: [<span class="pl-c1" style="color:#0086B3;">UTF8</span><span class="pl-k" style="color:#A71D5D;">.</span>CodeUnit] <span class="pl-k" style="color:#A71D5D;">var</span> isRepresentableAsASCII <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-c1" style="color:#0086B3;">true</span> <span class="pl-k" style="color:#A71D5D;">var</span> userSMTPServer: SecureSMTPServer</pre>
																																	</div>
<ul style="font-family:" font-size:16px;"="">
																																	<li>
																																		其它的“首字母缩略词”应按照一般单词处理，例如：
																																	</li>
																																		</ul>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">var</span> radarDetector: RadarScanner <span class="pl-k" style="color:#A71D5D;">var</span> enjoysScubaDiving <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-c1" style="color:#0086B3;">true</span></pre>
																																			</div>
																																			<h4 style="font-size:1.25em;font-family:;">
																																				<a id="user-content-314-方法可以共享一个公共的名字" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#314-%E6%96%B9%E6%B3%95%E5%8F%AF%E4%BB%A5%E5%85%B1%E4%BA%AB%E4%B8%80%E4%B8%AA%E5%85%AC%E5%85%B1%E7%9A%84%E5%90%8D%E5%AD%97"></a>3.1.4 方法可以共享一个公共的名字
																																			</h4>
<p style="font-family:" font-size:16px;"="">
	当方法表达相似的含义或它们用在不同的领域时，可以共享同一个名字。例如：
																																				</p>
<ul style="font-family:" font-size:16px;"="">
																																				<li>
																																					下面的方法是被提倡的，因为它们本质上表达的含义是相同的：
																																				</li>
																																					</ul>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> Shape { <span class="pl-c" style="color:#969896;">/// Returns `true` iff `other` is within the area of `self`.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">contains</span>(other: Point) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">Bool</span> { <span class="pl-k" style="color:#A71D5D;">...</span> } <span class="pl-c" style="color:#969896;">/// Returns `true` iff `other` is entirely within the area of `self`.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">contains</span>(other: Shape) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">Bool</span> { <span class="pl-k" style="color:#A71D5D;">...</span> } <span class="pl-c" style="color:#969896;">/// Returns `true` iff `other` is within the area of `self`.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">contains</span>(other: LineSegment) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">Bool</span> { <span class="pl-k" style="color:#A71D5D;">...</span> }
}

并且，由于几何和集合属于两个不同的技术领域，因此，同一个程序中，在集合中使用`contains`也是没问题的：

```swift <span class="pl-k" style="color:#A71D5D;">extension</span> Collection <span class="pl-k" style="color:#A71D5D;">where</span> Element <span class="pl-k" style="color:#A71D5D;">:</span> <span class="pl-c1" style="color:#0086B3;">Equatable</span> { <span class="pl-c" style="color:#969896;">/// Returns `true` iff `self` contains an element equal to</span> <span class="pl-c" style="color:#969896;">/// `sought`.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">contains</span>(sought: Element) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">Bool</span> { <span class="pl-k" style="color:#A71D5D;">...</span> }
}</pre>
																																						</div>
<p style="font-family:" font-size:16px;"="">
	但是，在下面的例子中，不同的index方法表达完全不同的语义，它们应该使用不同的名字：
																																							</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> Database { <span class="pl-c" style="color:#969896;">/// Rebuilds the database's search index</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">index</span>() { <span class="pl-k" style="color:#A71D5D;">...</span> } <span class="pl-c" style="color:#969896;">/// Returns the `n`th row in the given table.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">index</span>(n: <span class="pl-c1" style="color:#0086B3;">Int</span>, inTable: TableID) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> TableRow { <span class="pl-k" style="color:#A71D5D;">...</span> }
}</pre>
																																								</div>
<p style="font-family:" font-size:16px;"="">
	最后，避免“通过方法的返回值”实施重载行为，它们会在使用type inference的时候，带来歧义。
																																									</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> Box { <span class="pl-c" style="color:#969896;">/// Returns the `Int` stored in `self`, if any, and</span> <span class="pl-c" style="color:#969896;">/// `nil` otherwise.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">value</span>() <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">Int</span>? { <span class="pl-k" style="color:#A71D5D;">...</span> } <span class="pl-c" style="color:#969896;">/// Returns the `String` stored in `self`, if any, and</span> <span class="pl-c" style="color:#969896;">/// `nil` otherwise.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">value</span>() <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">String</span>? { <span class="pl-k" style="color:#A71D5D;">...</span> }
}</pre>
																																										</div>
																																										<h3 style="font-size:1.5em;font-family:;">
																																											<a id="user-content-32-关于参数" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#32-%E5%85%B3%E4%BA%8E%E5%8F%82%E6%95%B0"></a>3.2 关于参数
																																										</h3>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">move</span>(<span class="pl-en" style="color:#795DA3;">from</span> <span class="pl-smi">start</span>: Point, <span class="pl-en" style="color:#795DA3;">to</span> <span class="pl-smi">end</span>: Point)</pre>
																																									</div>
																																									<h4 style="font-size:1.25em;font-family:;">
																																										<a id="user-content-321-让参数名为文档服务" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#321-%E8%AE%A9%E5%8F%82%E6%95%B0%E5%90%8D%E4%B8%BA%E6%96%87%E6%A1%A3%E6%9C%8D%E5%8A%A1"></a>3.2.1 让参数名为文档服务
																																									</h4>
<p style="font-family:" font-size:16px;"="">
	尽管在函数或方法被调用的时候，参数名并不会出现，但它们对解释函数或方法的用途有重要作用。
																																								</p>
<p style="font-family:" font-size:16px;"="">
	因此，选择那些可以让文档更易读的参数名。例如，下面的例子里，注释文档读起来就很自然：
																																									</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Return an `Array` containing the elements of `self`</span> <span class="pl-c" style="color:#969896;">/// that satisfy `predicate`.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">filter</span>(<span class="pl-en" style="color:#795DA3;">_</span> <span class="pl-smi">predicate</span>: (Element) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">Bool</span>) -&gt; [Generator.Element]</pre>
																																										</div>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Replace the given `subRange` of elements with `newElements`.</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">replaceRange</span>(<span class="pl-en" style="color:#795DA3;">_</span> <span class="pl-smi">subRange</span>: <span class="pl-c1" style="color:#0086B3;">Range</span>, <span class="pl-en" style="color:#795DA3;">with</span> <span class="pl-smi">newElements</span>: [E])</pre>
																																									</div>
<p style="font-family:" font-size:16px;"="">
	而下面这些名字编写的文档，既不易读，还会带来语法错误：
																																								</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Return an `Array` containing the elements of `self`</span> <span class="pl-c" style="color:#969896;">/// that satisfy `includedInResult`.</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">filter</span>(<span class="pl-en" style="color:#795DA3;">_</span> <span class="pl-smi">includedInResult</span>: (Element) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">Bool</span>) -&gt; [Generator.Element] <span class="pl-c" style="color:#969896;">/// Replace the range of elements indicated by `r` with</span> <span class="pl-c" style="color:#969896;">/// the contents of `with`.</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">replaceRange</span>(<span class="pl-en" style="color:#795DA3;">_</span> <span class="pl-smi">r</span>: <span class="pl-c1" style="color:#0086B3;">Range</span>, with: [E])</pre>
																																							</div>
																																							<h4 style="font-size:1.25em;font-family:;">
																																								<a id="user-content-322-使用默认参数简化绝大多数的应用场景" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#322-%E4%BD%BF%E7%94%A8%E9%BB%98%E8%AE%A4%E5%8F%82%E6%95%B0%E7%AE%80%E5%8C%96%E7%BB%9D%E5%A4%A7%E5%A4%9A%E6%95%B0%E7%9A%84%E5%BA%94%E7%94%A8%E5%9C%BA%E6%99%AF"></a>3.2.2 使用默认参数简化绝大多数的应用场景
																																							</h4>
<p style="font-family:" font-size:16px;"="">
	如果一个参数在绝大多数时候都会使用同一个值，应该考虑为它指定默认值。
																																						</p>
<p style="font-family:" font-size:16px;"="">
	参数默认值可以通过隐藏次要信息提高代码的可读性，例如：
																																							</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">let</span> order <span class="pl-k" style="color:#A71D5D;">=</span> lastName<span class="pl-k" style="color:#A71D5D;">.</span>compare(
    royalFamilyName, options: [], range: <span class="pl-c1" style="color:#0086B3;">nil</span>, locale: <span class="pl-c1" style="color:#0086B3;">nil</span>)</pre>
																																								</div>
<p style="font-family:" font-size:16px;"="">
	（如果后三个参数都有默认值），compare调用读起来就会简单的多：
																																									</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">let</span> order <span class="pl-k" style="color:#A71D5D;">=</span> lastName<span class="pl-k" style="color:#A71D5D;">.</span>compare(royalFamilyName)</pre>
																																										</div>
<p style="font-family:" font-size:16px;"="">
	另外，如果你之前使用过方法家族（method families），你就更应该考虑使用是否可以用带有默认参数的方法来替代它们。这不仅可以帮助开发者更容易了解API的用法，也可以减轻对“家族成员”的认知负担。例如：
																																											</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> <span class="pl-c1" style="color:#0086B3;">String</span> { <span class="pl-c" style="color:#969896;">/// ...description...</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">compare</span>(
        other: <span class="pl-c1" style="color:#0086B3;">String</span>, options: CompareOptions <span class="pl-k" style="color:#A71D5D;">=</span> [],
        range: <span class="pl-c1" style="color:#0086B3;">Range</span>? <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-c1" style="color:#0086B3;">nil</span>, locale: Locale? <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-c1" style="color:#0086B3;">nil</span> ) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Ordering
}</pre>
																																												</div>
<p style="font-family:" font-size:16px;"="">
	尽管上面的compare看上去并不简单，但它总比下面的这个方法家族看上去简单多了：
																																													</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> <span class="pl-c1" style="color:#0086B3;">String</span> { <span class="pl-c" style="color:#969896;">/// ...description 1...</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">compare</span>(other: <span class="pl-c1" style="color:#0086B3;">String</span>) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Ordering <span class="pl-c" style="color:#969896;">/// ...description 2...</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">compare</span>(other: <span class="pl-c1" style="color:#0086B3;">String</span>, options: CompareOptions) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Ordering <span class="pl-c" style="color:#969896;">/// ...description 3...</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">compare</span>(
        other: <span class="pl-c1" style="color:#0086B3;">String</span>, options: CompareOptions, range: <span class="pl-c1" style="color:#0086B3;">Range</span>) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Ordering <span class="pl-c" style="color:#969896;">/// ...description 4...</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">compare</span>(
        other: <span class="pl-c1" style="color:#0086B3;">String</span>, options: StringCompareOptions,
        range: <span class="pl-c1" style="color:#0086B3;">Range</span>, locale: Locale) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> Ordering
}</pre>
																																														</div>
<p style="font-family:" font-size:16px;"="">
	方法家族中的每一个成员都需要单独的文档注释，都需要开发者去了解。为了能在调用时确认使用的成员，开发者不仅需要了解家族中的每一个方法，还偶尔会被foo(bar: nil)和foo()之间的差别吓一跳。因此，在一堆“看上去都差不多”的方法中，指出到底调用了哪个方法是一件让人头疼的事情。而用一个方法，合理搭配上默认参数，可以极大改进开发体验。
																																															</p>
																																															<h4 style="font-size:1.25em;font-family:;">
																																																<a id="user-content-323-倾向于从参数列表的末尾开始安排带有默认值的参数" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#323-%E5%80%BE%E5%90%91%E4%BA%8E%E4%BB%8E%E5%8F%82%E6%95%B0%E5%88%97%E8%A1%A8%E7%9A%84%E6%9C%AB%E5%B0%BE%E5%BC%80%E5%A7%8B%E5%AE%89%E6%8E%92%E5%B8%A6%E6%9C%89%E9%BB%98%E8%AE%A4%E5%80%BC%E7%9A%84%E5%8F%82%E6%95%B0"></a>3.2.3 倾向于从参数列表的末尾开始安排带有默认值的参数
																																															</h4>
<p style="font-family:" font-size:16px;"="">
	通常，如果参数没有默认值，它会对方法的执行语义有更为重要的影响。并且，把带有默认值的参数放在最后，可以让方法的调用方式更为一致。
																																														</p>
																																														<h3 style="font-size:1.5em;font-family:;">
																																															<a id="user-content-33-关于参数label" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#33-%E5%85%B3%E4%BA%8E%E5%8F%82%E6%95%B0label"></a>3.3 关于参数Label
																																														</h3>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">move</span>(<span class="pl-en" style="color:#795DA3;">from</span> <span class="pl-smi">start</span>: Point, <span class="pl-en" style="color:#795DA3;">to</span> <span class="pl-smi">end</span>: Point)
x<span class="pl-k" style="color:#A71D5D;">.</span><span class="pl-c1" style="color:#0086B3;">move</span>(from: x, to: y)</pre>
																																													</div>
																																													<h4 style="font-size:1.25em;font-family:;">
																																														<a id="user-content-331-当区分参数没有意义时忽略所有的参数label" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#331-%E5%BD%93%E5%8C%BA%E5%88%86%E5%8F%82%E6%95%B0%E6%B2%A1%E6%9C%89%E6%84%8F%E4%B9%89%E6%97%B6%E5%BF%BD%E7%95%A5%E6%89%80%E6%9C%89%E7%9A%84%E5%8F%82%E6%95%B0label"></a>3.3.1 当区分参数没有意义时，忽略所有的参数label
																																													</h4>
<p style="font-family:" font-size:16px;"="">
	例如在下面的两个方法里，区分参数时没意义的，它们的所有参数都不应该带有label：
																																												</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c1" style="color:#0086B3;">min</span>(number1, number2), <span class="pl-c1" style="color:#0086B3;">zip</span>(sequence1, sequence2)</pre>
																																											</div>
																																											<h4 style="font-size:1.25em;font-family:;">
																																												<a id="user-content-332-如果初始化方法执行了不会带来信息丢失的类型转换应该忽略初始化方法第一个参数的label" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#332-%E5%A6%82%E6%9E%9C%E5%88%9D%E5%A7%8B%E5%8C%96%E6%96%B9%E6%B3%95%E6%89%A7%E8%A1%8C%E4%BA%86%E4%B8%8D%E4%BC%9A%E5%B8%A6%E6%9D%A5%E4%BF%A1%E6%81%AF%E4%B8%A2%E5%A4%B1%E7%9A%84%E7%B1%BB%E5%9E%8B%E8%BD%AC%E6%8D%A2%E5%BA%94%E8%AF%A5%E5%BF%BD%E7%95%A5%E5%88%9D%E5%A7%8B%E5%8C%96%E6%96%B9%E6%B3%95%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E7%9A%84label"></a>3.3.2 如果初始化方法执行了不会带来信息丢失的类型转换，应该忽略初始化方法第一个参数的label
																																											</h4>
<p style="font-family:" font-size:16px;"="">
	例如：Int64(someUint32)
																																										</p>
<p style="font-family:" font-size:16px;"="">
	如果函数的功能是执行类型转换，那么第一个参数应该总是源类型（source of conversion），例如：
																																											</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> <span class="pl-c1" style="color:#0086B3;">String</span> { <span class="pl-c" style="color:#969896;">// Convert `x` into its textual representation in the given radix</span> <span class="pl-k" style="color:#A71D5D;">init</span>(_ x: BigInt, radix: <span class="pl-c1" style="color:#0086B3;">Int</span> <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-c1" style="color:#0086B3;">10</span>)   ← Note the initial underscore
}

text <span class="pl-k" style="color:#A71D5D;">=</span> <span class="pl-s" style="color:#183691;"><span class="pl-pds">"</span>The value is: <span class="pl-pds">"</span></span> text <span class="pl-k" style="color:#A71D5D;">+=</span> <span class="pl-c1" style="color:#0086B3;">String</span>(veryLargeNumber)
text <span class="pl-k" style="color:#A71D5D;">+=</span> <span class="pl-s" style="color:#183691;"><span class="pl-pds">"</span> and in hexadecimal, it's<span class="pl-pds">"</span></span> text <span class="pl-k" style="color:#A71D5D;">+=</span> <span class="pl-c1" style="color:#0086B3;">String</span>(veryLargeNumber, radix: <span class="pl-c1" style="color:#0086B3;">16</span>)</pre>
																																												</div>
<p style="font-family:" font-size:16px;"="">
	如果类型转换会带来信息丢失，应该在参数前面添加一个描述信息处理方式的label，例如：
																																													</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">extension</span> <span class="pl-c1" style="color:#0086B3;">UInt32</span> { <span class="pl-c" style="color:#969896;">/// Creates an instance having the specified `value`.</span> <span class="pl-k" style="color:#A71D5D;">init</span>(_ value: <span class="pl-c1" style="color:#0086B3;">Int16</span>)            ← Widening, so no label <span class="pl-c" style="color:#969896;">/// Creates an instance having the lowest 32 bits of `source`.</span> <span class="pl-k" style="color:#A71D5D;">init</span>(truncating source: <span class="pl-c1" style="color:#0086B3;">UInt64</span>) <span class="pl-c" style="color:#969896;">/// Creates an instance having the nearest representable</span> <span class="pl-c" style="color:#969896;">/// approximation of `valueToApproximate`.</span> <span class="pl-k" style="color:#A71D5D;">init</span>(saturating valueToApproximate: <span class="pl-c1" style="color:#0086B3;">UInt64</span>)
}</pre>
																																														</div>
																																														<h4 style="font-size:1.25em;font-family:;">
																																															<a id="user-content-333-如果第一个参数在方法被调用时形成了介词短语应该给第一个参数添加label" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#333-%E5%A6%82%E6%9E%9C%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E5%9C%A8%E6%96%B9%E6%B3%95%E8%A2%AB%E8%B0%83%E7%94%A8%E6%97%B6%E5%BD%A2%E6%88%90%E4%BA%86%E4%BB%8B%E8%AF%8D%E7%9F%AD%E8%AF%AD%E5%BA%94%E8%AF%A5%E7%BB%99%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E6%B7%BB%E5%8A%A0label"></a>3.3.3 如果第一个参数在方法被调用时形成了介词短语，应该给第一个参数添加label
																																														</h4>
<p style="font-family:" font-size:16px;"="">
	并且，参数的label也应该用介词开头，例如：x.removeBoxes(havingLength: 12)。
																																															</p>
<p style="font-family:" font-size:16px;"="">
	但是这条也有例外：当方法的前两个参数一起表达一个动作的抽象时，应该忽略第一个参数的label前面的介词。
																																														</p>
<p style="font-family:" font-size:16px;"="">
	例如，下面的这两个例子，它们的第一个参数都不应该以介词开头：
																																															</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>a<span class="pl-k" style="color:#A71D5D;">.</span><span class="pl-c1" style="color:#0086B3;">move</span>(toX: b, y: c)
a<span class="pl-k" style="color:#A71D5D;">.</span>fade(fromRed: b, green: c, blue: d)</pre>
																																																</div>
<p style="font-family:" font-size:16px;"="">
	遇到这种情况时，我们应该把介词放到参数label前面，这样可以更清楚的表达要执行的动作，例如：
																																																	</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>a<span class="pl-k" style="color:#A71D5D;">.</span>moveTo(x: b, y: c)
a<span class="pl-k" style="color:#A71D5D;">.</span>fadeFrom(red: b, green: c, blue: d)</pre>
																																																		</div>
																																																		<h4 style="font-size:1.25em;font-family:;">
																																																			<a id="user-content-334-否则如果第一个参数在方法调用时形成了一个语法正确的短语就忽略第一个参数的label" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#334-%E5%90%A6%E5%88%99%E5%A6%82%E6%9E%9C%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E5%9C%A8%E6%96%B9%E6%B3%95%E8%B0%83%E7%94%A8%E6%97%B6%E5%BD%A2%E6%88%90%E4%BA%86%E4%B8%80%E4%B8%AA%E8%AF%AD%E6%B3%95%E6%AD%A3%E7%A1%AE%E7%9A%84%E7%9F%AD%E8%AF%AD%E5%B0%B1%E5%BF%BD%E7%95%A5%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E7%9A%84label"></a>3.3.4 否则，如果第一个参数（在方法调用时）形成了一个语法正确的短语，就忽略第一个参数的label
																																																		</h4>
<p style="font-family:" font-size:16px;"="">
	并且，应该在方法名后面添加必要的前置单词。例如：x.addSubview(y)。
																																																			</p>
<p style="font-family:" font-size:16px;"="">
	这条指南的另外一个含义是，如果第一个参数不能在调用时和函数名形成语法正确的短语，它就应该有一个label，例如：
																																																		</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>view<span class="pl-k" style="color:#A71D5D;">.</span>dismiss(animated: <span class="pl-c1" style="color:#0086B3;">false</span>) <span class="pl-k" style="color:#A71D5D;">let</span> text <span class="pl-k" style="color:#A71D5D;">=</span> words<span class="pl-k" style="color:#A71D5D;">.</span><span class="pl-c1" style="color:#0086B3;">split</span>(maxSplits: <span class="pl-c1" style="color:#0086B3;">12</span>) <span class="pl-k" style="color:#A71D5D;">let</span> studentsByName <span class="pl-k" style="color:#A71D5D;">=</span> students<span class="pl-k" style="color:#A71D5D;">.</span>sorted(
    isOrderedBefore: Student<span class="pl-k" style="color:#A71D5D;">.</span>namePrecedes)</pre>
																																																	</div>
<p style="font-family:" font-size:16px;"="">
	这里还有一点要强调的是，在调用时（忽略掉第一个参数的label）形成的短语不仅要语法正确，还要表达正确、无歧义的语义。例如，下面这些例子，虽然语法正确，但却是有歧义的（因此，我们不应该忽略第一个参数的label）：
																																																</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>view<span class="pl-k" style="color:#A71D5D;">.</span>dismiss(<span class="pl-c1" style="color:#0086B3;">false</span>)   Don't dismiss? Dismiss a <span class="pl-c1" style="color:#0086B3;">Bool</span>?
words<span class="pl-k" style="color:#A71D5D;">.</span><span class="pl-c1" style="color:#0086B3;">split</span>(<span class="pl-c1" style="color:#0086B3;">12</span>)       Split the number <span class="pl-c1" style="color:#0086B3;">12</span></pre>
																																															</div>
																																															<h4 style="font-size:1.25em;font-family:;">
																																																<a id="user-content-335除了第一个参数之外为所有其它参数设置label" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#335%E9%99%A4%E4%BA%86%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%8F%82%E6%95%B0%E4%B9%8B%E5%A4%96%E4%B8%BA%E6%89%80%E6%9C%89%E5%85%B6%E5%AE%83%E5%8F%82%E6%95%B0%E8%AE%BE%E7%BD%AElabel"></a>3.3.5（除了第一个参数之外），为所有其它参数设置label
																																															</h4>
																																															<h2 style="font-size:1.75em;font-family:;">
																																																<a id="user-content-第四部分-特殊情况" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#%E7%AC%AC%E5%9B%9B%E9%83%A8%E5%88%86-%E7%89%B9%E6%AE%8A%E6%83%85%E5%86%B5"></a>第四部分 特殊情况
																																															</h2>
																																															<h3 style="font-size:1.5em;font-family:;">
																																																<a id="user-content-41-在你的api里为closure的参数和tuple成员设置label" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#41-%E5%9C%A8%E4%BD%A0%E7%9A%84api%E9%87%8C%E4%B8%BAclosure%E7%9A%84%E5%8F%82%E6%95%B0%E5%92%8Ctuple%E6%88%90%E5%91%98%E8%AE%BE%E7%BD%AElabel"></a>4.1 在你的API里，为closure的参数和tuple成员设置label
																																															</h3>
<p style="font-family:" font-size:16px;"="">
	为这些元素设置的label好处有二：
																																														</p>
<ol style="font-family:" font-size:16px;"="">
																																														<li>
																																															可以极大提升文档注释的表达能力；
																																														</li>
																																														<li>
																																															让访问tuple成员的代码更易读；
																																														</li>
																																															</ol>
<p style="font-family:" font-size:16px;"="">
	例如：
																																																</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-c" style="color:#969896;">/// Ensure that we hold uniquely-referenced storage for at least</span> <span class="pl-c" style="color:#969896;">/// `requestedCapacity` elements.</span> <span class="pl-c" style="color:#969896;">///</span> <span class="pl-c" style="color:#969896;">/// If more storage is needed, `allocate` is called with</span> <span class="pl-c" style="color:#969896;">/// `byteCount` equal to the number of maximally-aligned</span> <span class="pl-c" style="color:#969896;">/// bytes to allocate.</span> <span class="pl-c" style="color:#969896;">///</span> <span class="pl-c" style="color:#969896;">/// - Returns:</span> <span class="pl-c" style="color:#969896;">///   - reallocated: `true` iff a new block of memory</span> <span class="pl-c" style="color:#969896;">///     was allocated.</span> <span class="pl-c" style="color:#969896;">///   - capacityChanged: `true` iff `capacity` was updated.</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">ensureUniqueStorage</span>( <span class="pl-en" style="color:#795DA3;">minimumCapacity</span> <span class="pl-smi">requestedCapacity</span>: <span class="pl-c1" style="color:#0086B3;">Int</span>,
    allocate: (byteCount: <span class="pl-c1" style="color:#0086B3;">Int</span>) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> <span class="pl-c1" style="color:#0086B3;">UnsafePointer</span>&lt;<span class="pl-c1" style="color:#0086B3;">Void</span>&gt;
) <span class="pl-k" style="color:#A71D5D;">-&gt;</span> (reallocated: <span class="pl-c1" style="color:#0086B3;">Bool</span>, capacityChanged: <span class="pl-c1" style="color:#0086B3;">Bool</span>)</pre>
																																																	</div>
<p style="font-family:" font-size:16px;"="">
	尽管从技术上来说，我们在closure中使用的是<span style="font-weight:bolder;">参数label（这里指byteCount）</span>，但在注释文档中，我们应该把它当做<span style="font-weight:bolder;">参数名称</span>来使用。
																																																		</p>
<p style="font-family:" font-size:16px;"="">
	在函数内部调用这个closure时，这个调用形成的表达方式，和调用一个“名称中不包含第一个参数（注：这应该是相对于名称中会带有介词的函数名而言的）”的函数是一致的：
																																																	</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre>allocate(byteCount: newCount <span class="pl-k" style="color:#A71D5D;">*</span> elementSize)</pre>
																																																</div>
																																																<h3 style="font-size:1.5em;font-family:;">
																																																	<a id="user-content-42-留意那些无约束类型带来的多态效果unconstrained-polymorphism" class="anchor" href="https://github.com/Boxue/swift-api-design-guidelines/blob/master/swift-api-guidelines.md#42-%E7%95%99%E6%84%8F%E9%82%A3%E4%BA%9B%E6%97%A0%E7%BA%A6%E6%9D%9F%E7%B1%BB%E5%9E%8B%E5%B8%A6%E6%9D%A5%E7%9A%84%E5%A4%9A%E6%80%81%E6%95%88%E6%9E%9Cunconstrained-polymorphism"></a>4.2 留意那些无约束类型带来的多态效果（unconstrained polymorphism）
																																																</h3>
<p style="font-family:" font-size:16px;"="">
	特别是Any，AnyObject或者泛型参数，它们很容易在方法重载时意外带来歧义。例如，考虑下面两个重载的方法：
																																															</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">struct</span> <span class="pl-c1" style="color:#0086B3;">Array</span> { <span class="pl-c" style="color:#969896;">/// Inserts `newElement` at `self.endIndex`.</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">append</span>(newElement: Element) <span class="pl-c" style="color:#969896;">/// Inserts the contents of `newElements`, in order, at</span> <span class="pl-c" style="color:#969896;">/// `self.endIndex`.</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">append</span>&lt;
        S <span class="pl-k" style="color:#A71D5D;">:</span> <span class="pl-c1" style="color:#0086B3;">SequenceType</span> <span class="pl-k" style="color:#A71D5D;">where</span> S<span class="pl-k" style="color:#A71D5D;">.</span>Generator<span class="pl-k" style="color:#A71D5D;">.</span>Element <span class="pl-k" style="color:#A71D5D;">==</span> Element
    &gt;(newElements: S)
}</pre>
																																																</div>
<p style="font-family:" font-size:16px;"="">
	这两个方法形成了一个语义家族（semantic family），它们的参数看上去是截然不同的。但是，当Array中Element的类型是Any时，一个单一的元素有可能和一个元素集合的类型是相同的。
																																																	</p>
<p style="font-family:" font-size:16px;"="">
	例如，在下面的例子里，我们究竟应该认为[2, 3, 4]是一个Any，还是把它理解为是一个[Any]呢？
																																																</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">var</span> values: [<span class="pl-c1" style="color:#0086B3;">Any</span>] <span class="pl-k" style="color:#A71D5D;">=</span> [<span class="pl-c1" style="color:#0086B3;">1</span>, <span class="pl-s" style="color:#183691;"><span class="pl-pds">"</span>a<span class="pl-pds">"</span></span>]
values<span class="pl-k" style="color:#A71D5D;">.</span>append([<span class="pl-c1" style="color:#0086B3;">2</span>, <span class="pl-c1" style="color:#0086B3;">3</span>, <span class="pl-c1" style="color:#0086B3;">4</span>]) <span class="pl-c" style="color:#969896;">// [1, "a", [2, 3, 4]] or [1, "a", 2, 3, 4]?</span></pre>
																																															</div>
<p style="font-family:" font-size:16px;"="">
	为了避免这个歧义，我们可以给第二个重载版本的参数，添加一个label：
																																																</p>
<div class="highlight highlight-source-swift" style="font-family:" font-size:16px;"="">
<pre><span class="pl-k" style="color:#A71D5D;">struct</span> <span class="pl-c1" style="color:#0086B3;">Array</span> { <span class="pl-c" style="color:#969896;">/// Inserts `newElement` at `self.endIndex`.</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">append</span>(newElement: Element) <span class="pl-c" style="color:#969896;">/// Inserts the contents of `newElements`, in order, at</span> <span class="pl-c" style="color:#969896;">/// `self.endIndex`.</span> <span class="pl-k" style="color:#A71D5D;">public</span> <span class="pl-k" style="color:#A71D5D;">mutating</span> <span class="pl-k" style="color:#A71D5D;">func</span> <span class="pl-en" style="color:#795DA3;">append</span>&lt;
        S <span class="pl-k" style="color:#A71D5D;">:</span> <span class="pl-c1" style="color:#0086B3;">SequenceType</span> <span class="pl-k" style="color:#A71D5D;">where</span> S<span class="pl-k" style="color:#A71D5D;">.</span>Generator<span class="pl-k" style="color:#A71D5D;">.</span>Element <span class="pl-k" style="color:#A71D5D;">==</span> Element
    &gt; (<span class="pl-en" style="color:#795DA3;">contentsOf</span> <span class="pl-smi">newElements</span>: S)
}</pre>
																																																	</div>
<p style="font-family:" font-size:16px;"="">
	注意到新添加的参数label是如何和文档注释匹配的了么？这样，编写文档注释实际上也是在提醒作者每个API的用途。
																																																		</p> </p>
			     </div>

 		</div>
	</div>
  </div>
  
  
	<div class="site-footer container clearfix">   
	     <ul class="site-footer-links">
	       
	         <li><a href="http://www.swiftv.cn/news/page/lianxi"  >友情链接：</a></li>
	         <li><a href="http://www.swiftv.net"  target="_blank"  >Swift的那点事</a></li>
	         <li><a href="http://Letsswift.com/"  target="_blank"  >一起Swift</a></li>
	         <li><a href="http://www.ucai.cn/index.php?app=home&mod=Public&act=blogroll"  target="_blank"  >优才网</a></li>
	         <li><a href="http://www.9ria.com/"  target="_blank"  >9Ria游戏开发者社区</a></li>
	         <li><a href="http://www.swiftvip.cn"  >Swift中文网</a></li>
	         <li><a href="http://www.swift51.com/"  target="_blank"  >雨燕社区</a></li>
	         <li><a href="http://www.rupeng.com/friendsLink.shtml"  target="_blank"  >如鹏网(.NET/JAVA)</a></li>
	         <li><a href="http://www.ruanman.net"  target="_blank"  >软曼网</a></li>
	         <li><a href="https://mos.meituan.com/doc/about"  target="_blank"  >美团云</a></li>
	         <li><a href="http://www.maiziedu.com/"  target="_blank"  >麦子学院</a></li>
	         <li><a href="http://www.superqq.com/"  target="_blank"  >刚刚在线</a></li>
	         <li><a href="http://wgh.me/"  target="_blank"  >Sally</a></li>
	         <li><a href="http://www.oneapm.com/"  target="_blank"  >应用性能管理</a></li>
	         <li><a href="http://www.51ios.net/"  target="_blank"  >51iOS</a></li>
	         <li><a href="https://boxueio.com/"  target="_blank"  >泊学-全栈自学之路</a></li>
	         <li><a href="http://www.xsteach.com/"  target="_blank"  >邢帅教育</a></li>
	         <li><a href="http://www.i3done.com/"  target="_blank"  >3Done</a></li>
	         <li><a href="http://www.wyzc.com/"  target="_blank"  >我赢职场</a></li>
	         <li><a href="../page/qun.html"  >QQ群公布</a></li>
	         <li><a href="../page/yijian.html"  target="_blank"  >用户体验持续改进计划</a></li>
	     </ul>
	  
	  <div class="alert text-center"><a href="http://www.miitbeian.gov.cn/" target="_blank"> 粤ICP备14044760-1</a></div>
	</div>
	
	<div><script>window._bd_share_config={"common":{"bdSnsKey":{"tsina":"3474175605"},"bdText":"SwiftV课堂，是我见过的最有氛围的Swift视频学习站，体验很棒！小伙伴要不要一起来学习？限免哟~#SwiftV课堂#","bdMini":"1","bdMiniList":false,"bdPic":"","bdStyle":"0","bdSize":"16"},"slide":{"type":"slide","bdImg":"3","bdPos":"left","bdTop":"214.5"}};with(document)0[(getElementsByTagName('head')[0]||body).appendChild(createElement('script')).src='http://bdimg.share.baidu.com/static/api/js/share.js?v=89860593.js?cdnversion='+~(-new Date()/36e5)];</script></div>



  
<div id="ScrollToTop" class="btnimg Button2" style="color: rgb(255, 255, 255);text-align: center; display: block; background-color: rgba(12, 173, 87, 0.69);padding: 11px; width: 60px;bottom:15px;">返回<br>顶部</div>
  <div id="login-modal" class="modal" data-url="/login/ajax"></div>
  <div id="modal" class="modal"></div>


<script src="http://static.vlms.cn/resources/js/jquery.form.min.js"></script>
<script src="http://static.vlms.cn/resources/js/bootstrapValidator.min.js"></script>
<script src="http://static.vlms.cn/resources/bootstrap/js/bootstrap.min.js"></script>
<script src="http://static.vlms.cn/resources/js/autocomplete.js"></script>
<script src="http://static.vlms.cn/resources/js/bootstrap-notify.js"></script>





  
  <!-- 统计代码 -->
  <script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "//hm.baidu.com/hm.js?1e733c39d359b2149cd361e97999460b";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
  ga('create', 'UA-52703035-1', 'auto');
  ga('send', 'pageview');
</script>


  </body>
</html>